A.3 Adding hyperlink types

Org has a large number of hyperlink types built-in (see Hyperlinks). If you would like to add new link types, Org provides an interface for doing so. Let’s look at an example file, org-man.el, that will add support for creating links like ‘[[man:printf][The printf manpage]]’ to show Unix manual pages inside Emacs:

;;; org-man.el - Support for links to manpages in Org

(require 'org)

(org-add-link-type "man" 'org-man-open)
(add-hook 'org-store-link-functions 'org-man-store-link)

(defcustom org-man-command 'man
  "The Emacs command to be used to display a man page."
  :group 'org-link
  :type '(choice (const man) (const woman)))

(defun org-man-open (path)
  "Visit the manpage on PATH.
PATH should be a topic that can be thrown at the man command."
  (funcall org-man-command path))

(defun org-man-store-link ()
  "Store a link to a manpage."
  (when (memq major-mode '(Man-mode woman-mode))
    ;; This is a man page, we do make this link
    (let* ((page (org-man-get-page-name))
           (link (concat "man:" page))
           (description (format "Manpage for %s" page)))
      (org-store-link-props
       :type "man"
       :link link
       :description description))))

(defun org-man-get-page-name ()
  "Extract the page name from the buffer name."
  ;; This works for both `Man-mode' and `woman-mode'.
  (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
      (match-string 1 (buffer-name))
    (error "Cannot create link to this man page")))

(provide 'org-man)

;;; org-man.el ends here

You would activate this new link type in .emacs with

(require 'org-man)

Let’s go through the file and see what it does.

1. It does (require 'org) to make sure that org.el has been loaded.
2. The next line calls org-add-link-type to define a new link type with prefix ‘man’. The call also contains the name of a function that will be called to follow such a link.
3. The next line adds a function to org-store-link-functions, in order to allow the command C-c l to record a useful link in a buffer displaying a man page.

The rest of the file defines the necessary variables and functions. First there is a customization variable that determines which Emacs command should be used to display man pages. There are two options, man and woman. Then the function to follow a link is defined. It gets the link path as an argument—in this case the link path is just a topic for the manual command. The function calls the value of org-man-command to display the man page.

Finally the function org-man-store-link is defined. When you try to store a link with C-c l, this function will be called to try to make a link. The function must first decide if it is supposed to create the link for this buffer type; we do this by checking the value of the variable major-mode. If not, the function must exit and return the value nil. If yes, the link is created by getting the manual topic from the buffer name and prefixing it with the string ‘man:’. Then it must call the command org-store-link-props and set the :type and :link properties. Optionally you can also set the :description property to provide a default for the link description when the link is later inserted into an Org buffer with C-c C-l.

When it makes sense for your new link type, you may also define a function org-PREFIX-complete-link that implements special (e.g., completion) support for inserting such a link with C-c C-l. Such a function should not accept any arguments, and return the full link with prefix.